
import sys
import datetime

def cffl(level=1):
    '''
     modification based on : 
     Determining Current Function Name
     http://code.activestate.com/recipes/66062/

     sys._getframe() -- returns a frame object, whose attribute
     f_code is a code object, whose attribute co_name is the name
     the frame and code objects also offer other useful information

     also, by calling sys._getframe(1), you can get this information
     for the *caller* of the current function.  So you can package
     this functionality up into your own handy functions:
    '''
    # caller function name
    fun = sys._getframe(level).f_code.co_name
    # caller function line
    lin = sys._getframe(level).f_lineno
    # caller function file name
    filepath = sys._getframe(level).f_code.co_filename
    if string.find(filepath,'/') <> -1:
        fin = string.split(filepath, '/')[-1]
    if string.find(filepath,'\\') <> -1:
        fin = string.split(filepath, '\\')[-1]
    # date time
    dtm = str(datetime.datetime.now())[:23]

    return {'FILE': fin, 'FUNCTION': fun, 'LINE': lin, 'DTIME' : dtm}

def docfile(msg=''):
    ''' automatized production of up to date documentation file
     ideas behind concept:
     - reuse of code comments for automatized creation of documentation 
     - automatized remodelling and documentation of process flow
     - details logged : file, function, line number, datetime, msg(coments text)

     basic rules to be followed:
     - avoid using in repeating sequences
     - do not comment trivial actions (except when part of wider explanation)
     - stay on high logic level; lower logic commented only if unavoidable
    '''
    # prepare information
    res = {'MSG' : msg}
    res.update(cffl(2))

    return res

def myFunction():
    print docfile ('do ...')

if __name__ == '__main__':
    ''' '''
    myFunction()
    #{'MSG': 'do ...', 'FUNCTION': 'myFunction', 'LINE': 50, 'DTIME': '2008-08-02 16:38:46.960', 'FILE': 'C:\\AFT\\pepe\\p_utils\\comments.py'}
